001 /*
002 * Copyright 2005 Stephen J. McConnell
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
013 * implied.
014 *
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019 package net.dpml.library;
020
021 import java.io.File;
022
023 import net.dpml.library.info.Scope;
024 import net.dpml.library.info.ResourceDirective.Classifier;
025
026 import net.dpml.transit.Artifact;
027
028 import net.dpml.lang.Category;
029 import net.dpml.lang.Version;
030
031 import net.dpml.util.Resolver;
032
033 /**
034 * The Resource interface describes infomation about a published resource.
035 *
036 * @author <a href="http://www.dpml.net">The Digital Product Meta Library</a>
037 * @version 1.0.0
038 */
039 public interface Resource extends Dictionary, Resolver
040 {
041 /**
042 * Return the singleton library.
043 * @return the library
044 */
045 Library getLibrary();
046
047 /**
048 * Return the name of the resource.
049 * @return the resource name
050 */
051 String getName();
052
053 /**
054 * Return the resource version.
055 * @return the version
056 */
057 String getVersion();
058
059 /**
060 * Return the statutory resource version.
061 * @return the version
062 */
063 String getStatutoryVersion();
064
065 /**
066 * Return the decimal version.
067 * @return the version
068 */
069 Version getDecimalVersion();
070
071 /**
072 * Return the fully qualified path to the resource.
073 * @return the path
074 */
075 String getResourcePath();
076
077 /**
078 * Return the basedir for this resource.
079 * @return the base directory (possibly null)
080 */
081 File getBaseDir();
082
083 /**
084 * Return the info block.
085 * @return the info block
086 */
087 Info getInfo();
088
089 /**
090 * Return the resource classifier.
091 * @return the classifier (LOCAL, EXTERNAL or ANONYMOUS)
092 */
093 Classifier getClassifier();
094
095 /**
096 * Return the expanded array of types associated with the resource.
097 * The returned array is a function of the types declared by a resource
098 * expanded relative to any types implied by processor dependencies.
099 * @return the type array
100 */
101 Type[] getTypes();
102
103 /**
104 * Test if this resource is associated with a type of the supplied name.
105 * @param type the type id
106 * @return TRUE if this resource produces an artifact of the supplied type
107 */
108 boolean isa( String type );
109
110 /**
111 * Return a resource type relative to a supplied type id.
112 * @param id the type name to retrieve
113 * @return the type instance
114 */
115 Type getType( String id );
116
117 /**
118 * Construct an artifact for the supplied type.
119 * @param type the resource type id
120 * @return the artifact
121 */
122 Artifact getArtifact( String type );
123
124 /**
125 * Construct an unversion link artifact for the supplied type.
126 * @param type the resource type id
127 * @return the link artifact
128 */
129 Artifact getLinkArtifact( String type );
130
131 /**
132 * Return the enclosing parent module.
133 * @return the enclosing module of null if this a top-level module.
134 */
135 Module getParent();
136
137 /**
138 * Return an array of resource that are providers to this resource.
139 * @param scope the operational scope
140 * @param expand if true include transitive dependencies
141 * @param sort if true the array will sorted relative to dependencies
142 * @return the resource providers
143 */
144 Resource[] getProviders( Scope scope, boolean expand, boolean sort );
145
146 /**
147 * Return an array of resource that are providers to this resource. If
148 * the supplied scope is BUILD the returned resource array is equivalent
149 * <src>getProviders( Scope.BUILD, .. )</src>. If the scope is RUNTIME
150 * the returned resource array includes BUILD and RUNTIME resources. If
151 * the scope is TEST the returned array includes BUILD, RUNTIME and TEST
152 * resources.
153 * @param scope the scope of aggregation to be applied to the selection
154 * @param expand if TRUE include transitive dependencies
155 * @param sort if true the array will sorted relative to dependencies
156 * @return the resource providers
157 */
158 Resource[] getAggregatedProviders( Scope scope, boolean expand, boolean sort );
159
160 /**
161 * Return a sorted and filtered array of providers. Resources not declaring
162 * the "jar" type as a produced type are excluded from selection. The
163 * resource array will include transitive dependencies. The method is
164 * suitable for the construction of build and test phase classloaders.
165 *
166 * @param scope the aggregation scope
167 * @return the scoped resource chain
168 */
169 Resource[] getClasspathProviders( Scope scope );
170
171 /**
172 * Return an array of runtime providers filtered relative to a supplied
173 * classloading category. Resources not declaring the "jar" type as a
174 * produced type are excluded from selection. The resource array returned
175 * from this operation is a sorted transitive sequence excluding all
176 * resource references by any category higher than the supplied category.
177 * This method is typically used to construct information suitable for
178 * the gerneration of plugin metadata.
179 *
180 * @param category the classloader category
181 * @return the category scoped resource chain
182 */
183 Resource[] getClasspathProviders( Category category );
184
185 /**
186 * Return an array of resources that are consumers of this resource.
187 * @param expand if true the returned array includes consumers associated
188 * through transitive dependency relationships, otherwise the array is
189 * limited to direct consumers
190 * @param sort if true the array is sorted relative to depenency relationships
191 * @return the array of consumer projects
192 */
193 Resource[] getConsumers( boolean expand, boolean sort );
194
195 /**
196 * Return an array of filters associated with the resource.
197 * @return the array of filters
198 */
199 Filter[] getFilters();
200
201 /**
202 * Return a filename using the layout strategy employed by the cache.
203 * @param id the artifact type
204 * @return the filename
205 */
206 String getLayoutPath( String id );
207
208 /**
209 * Return the array of production data.
210 * @return the associated production data
211 */
212 Data[] getData();
213 }